
//-----------------------------------------------------------------------------
//  
//  Package
//  
//-----------------------------------------------------------------------------

package 
{
	
	//-------------------------------------------------------------------------
	//  
	//  Imports
	//  
	//-------------------------------------------------------------------------
	
	import com.notna.utils.ImmutableArray;
	
	//-------------------------------------------------------------------------
	//  
	//  Class
	//  
	//-------------------------------------------------------------------------
	
	/**
	 * An interface that contains exposed methods for the ZMShell to implement. 
	 * Some are retroimplemented from the Shell class. This serves mainly as a 
	 * way to document all the exposed methods of the ZMShell in one place.
	 */
	public interface ExposedMethods
	{
		
		//---------------------------------------------------------------------
		//  
		//  Properties
		//  
		//---------------------------------------------------------------------
		
		//------------------------------
		//  history
		//------------------------------
		
		/**
		 * A history of all text input as an immutable array.
		 * 
		 * @return An array containing all text sent as input to the shell.
		 */
		function get history():ImmutableArray;
		
		//---------------------------------------------------------------------
		//  
		//  Methods
		//  
		//---------------------------------------------------------------------
		
		/**
		 * Prints out a description of the shell application.
		 * 
		 * @return The description of the shell application.
		 */
		function about():String;
		
		/**
		 * Clears the display.
		 */
		function clear():void;
		
		/**
		 * Evaluates the expression as ES4 code.
		 * 
		 * @param expression The code to be evaluated.
		 */
		function eval2(expression:String):void;
		
		/**
		 * Removes all text objects and destroys all listeners, rendering 
		 * the shell unusable. Dispatches a <code>ShellEvent</code> with 
		 * type <code>ShellEvent.EXIT</code>.
		 */
		function exit():void;
		
		/**
		 * Retrieves a class definition by its name.
		 * 
		 * @param name The name of the class.
		 * @return The class definition.
		 */
		function getClassByName(name:String):Class;
		
		/**
		 * Returns the time in milliseconds since the application began.
		 * 
		 * @return The time in milliseconds relative to the start of the application.
		 */
		function getTimer():uint;
		
		/**
		 * Loads (executes) the given file into the ZMEngine. If the file is a 
		 * text file containing a script, the script is evaluated. If the file 
		 * is a SWF or an SWC, it is loaded as a library.
		 * 
		 * A text file is unloaded (marked for garbage collection) as soon as
		 * it finishes evaluation. SWFs and SWCs must be unloaded manually via
		 * the returned hash code.
		 * 
		 * @param file The (absolute) filepath of the file to be loaded.
		 * @return The hash code used by the ZMEngine to reference the loaded 
		 * data if it is a SWC or SWF.
		 */
		function exec(filename:String):String;
		
		/**
		 * Unloads the data in the ZMEngine represented by the hash code.
		 * 
		 * @param hashCode
		 * @return <code>true</code> if the data was marked for garbage collection, 
		 * <code>false</code> otherwise.
		 */
		function kill(hashCode:String):Boolean;
		
		/**
		 * Prints the expression with a newline.
		 * 
		 * @param expression The expression to be printed.
		 */
		function print(... expressions):void;
		
		/**
		 * Resets the display, history, and the ZMEngine.
		 */
		function reset():void;
		
		/**
		 * Saves the ZMEngine history to a file.
		 * 
		 * @param filename The path of the file to save the history to.
		 * @param index The index to start concatenating the history. If the index exceeds
		 * the history, an empty file is written.
		 * @param length How many commands to concatenate. If the length index 
		 * is 0, then all history items from the index are concatenated.
		 */
		function save(filename:String, index:uint = 0, length:uint = 0):void;
	}
}